<!--slrpfmt2.htm-->
<HTML><HEAD>
<!--<BASE HREF="http://members.bellatlantic.net/~sweyer/newton/sloup/slrpfmt2.htm">-->
<TITLE>Continuations, Binary Resources</TITLE>
<META NAME="ISBN" 		CONTENT="slrpfmt2.htm">
<META NAME="SHORTTITLE" CONTENT="SloupRsrc">
<META NAME="AUTHOR"		CONTENT="Steve Weyer">
<META NAME="COPYRIGHT" 	CONTENT="&copy; 1993-98, S. Weyer">
<META NAME="_package.labels" 	CONTENT="'Books">
<META NAME="_package.compressed" CONTENT="true">
<META NAME="data.clickAddFile" 	CONTENT="func(x,y,href,obj)
begin
	PlaySound(@51); /*ROM_click*/
	GetRoot().|Sloup:TKnollSys|:?addFile(
		&quot;text/html&quot;, href, obj.item.data, nil);
end">
<META NAME="data.bitmap1.slp" CONTENT="clickAddfile">
</HEAD><BODY>

<H1><A NAME="Line Continuations">Line Continuations</A></H1>

<P>To make long entry specs (and data) easier to edit/view in a text editor,
and allow Sloup to minimize heap usage for very long entries, you can use
line continuations. Partial lines should end with a backslash \<BR>
Sloup concatenates these together (and provides feedback on the current
status of the "entry len") until it encounters a line without one. It does
slightly special processing for binary data. When splitting a line with \,
make sure your text editor doesn't auto-indent and add extra tabs to
subsequent lines.

<P>For regular data soups, I usually put a line continuation just before a
tab, so that the remaining lines for the entry are indented (begin with a
tab). See Names20.tab for an example.

<P>For Notes, \ is not used; a paragraph is concatenated until it encounters
a ----- (at least 5 -) or BYE! For NOS 2.x, each item in an outlines and
checkLists occurs on a separate line.

<H1><A NAME="Binary Resources">Binary Resources</A></H1>

<P>You can transfer bitmap, PICT, sound and IR (infrared) command resources
to the Newton, for example, to include in an application you are building
with <A HREF="../newtdev.htm">NewtDevEnv</A> or a book you are creating from
HTML with <A HREF="../newtscape.htm">Newt's Cape</A>.

<H2><A NAME="Bitmaps">Bitmaps</A></H2>

<P>Small bitmaps can be created by hand if you are patient and not binary
challenged; a tool like ResEdit on the Mac works pretty well to extract hex
strings. If you are a registered user of <A HREF="../newtscape.htm">Newt's
Cape</A>, you have access to Newt's Cape Graphic Converter which will
produce Sloup-compatible files for PICTs and bitmaps(icons).

<P>Let me know which other tools on Mac or other platforms you find useful
so I can share this info (see <A HREF="../toolinfo.htm">current tools</A>).
Since these binary hex text strings are often long, I almost always use line
continuations; in addition to regular line continuations that concatenate
the entry as text before processing, <A HREF="#Binary Line
Continuations">Binary Line Continuations</A> are more efficient (and will be
illustrated below).

<P>For example, the following example creates 3 identical entries for an "i"
graphic that can go in an info button.

<PRE><A HREF="bitmap1.slp">Bitmaps![{structure: 'slot, path: 'name, type: 'symbol},]
{name: 'symbol, width: "int", bitmap: "bitmap"}
REPLACE!name
infoIcon	5	700000007000000000000000F000000070000000700000007000000070000000F8000000
infoIcon2	5	7000000070000000000\
00000F00000007\
0000000700000007000000070000000F8000000
infoIcon3	5	!\
70000000\
70000000\
00000000\
F0000000\
70000000\
70000000\
70000000\
70000000\
F8000000
BYE!</A>
</PRE>

<P>The first line is the name of the soup -- Bitmaps. Since ! occurs, Sloup
creates the soup if it doesn't already exist. It also provides an expression
that is compiled to create an array of indexes -- it must be at least []. In
this example, we want the name slot (first column) to be indexed for direct
lookup/faster retrieval by some application -- for example, by Newt, Newt's
Cape or BitSound, or Sloup (for replacement).

<P>The second line is the entry description:

<DL>
<DT>name
<DD>a string which is converted to a symbol

<DT>width
<DD>actual integer width of the bitmap in pixels (for storage/transfer
purposes, this is "rounded up" to 32 pixel increments). Note: height is not
supplied -- the number of rows is computed from the bitmap

<DT>bitdepth
<DD>(optional: default: 1 = black and white). integer: black and white (1),
4-grays (2), 16-grays (4). see <A HREF="#Gray Scale Bitmaps">Gray Scale
Bitmaps</A>

<DT>bitmap
<DD>bitmap is a datatype which converts the ascii string into a binary
unicode format (because of memory limitations for large bitmaps, this field
must occur last)
</DL>

<P>The third line (REPLACE!name) is a command to replace an existing bitmap
objects with the same name (old entry is removed; new entry is added).

<P>The fourth line is an actual entry, with fields delimited by tabs.
infoIcon is the name (since this becomes a symbol, it's generally a good
idea to use only alphanumeric and underscore _ characters so that it's
easier to access later). width is 5, the bitmap occupies the remainder of
the same (long) line.

<H2><A NAME="Binary Line Continuations">Binary Line Continuations</A></H2>

<P>Before interpreting the bitmap, let's look at two other variations.
Depending on the length of the bitmap entry, and the capabilities/limits of
your text editor and terminal emulator, you may want lines that are no
longer than 72-80 characters.

<P>The next line that creates "infoIcon2" actually consists of 3 lines of
text. This line and the next are suffixed with \, regular <A HREF="#Line
Continuations">Line Continuations</A>. Sloup concatenates these three lines
together as text before processing it to produce an identical result (except
for name) as the first line. This form of line continuation can be used with
any tab-delimited text line.

<P>For bitmap or sound lines that are long, I would recommend a slight
variation, illustrated by "info icon3". End the final field on the first
line with !\ (! precedes \). Sloup converts the subsequent hex data
immediately into a binary (rather than a normal) string. This allows much
larger resources to be transferred. (The hex text encoding is ~2x the
original/eventual binary resource size). Note: for this to work, the number
of hex characters on a line <STRONG>must</STRONG> be even. (Check this with
your text editor's "Cursor position" command). Sloup provides feedback on
the current status of the "binary len".

<P>Some approximate (current) limits on these three methods:

<UL>
<LI>&lt;31K on a single line (but some terminal emulators truncate after 4K)
<LI>&lt;25K on multiple lines (as text) [concatenation overhead, heap limits]
<LI>&gt;63K on multiple lines (binary) [haven't tested any larger yet,
though this is close to the practical limit of what you can keep in heap or
store in a soup entry on 1.x Newtons; for 2.x Newtons, the limit should be
much larger since Sloup uses "virtual binary objects" to collect the data
</UL>

<H2><A NAME="Bitmap Structure">Bitmap Structure</A></H2>

<P>Here's how to interpret the bitmap string. Each hexadecimal character
(0-F) of the bitmap string represents 4 bits; each row is represented by a
multiple of 8 characters (32 bits). In the infoIcon example, the width is 5,
so each row has 8 characters (even though 27 bits in each row are unused; if
width is between 33 and 64, you would need 64 bits, or 16 characters for
each row, and so on). For clarity, "infoIcon3" was broken into rows of 8
characters each -- here it is expanded with a binary annotation (omitting
trailing zeros):

<PRE>70000000 // 0111 00...
70000000 // 0111 00...
00000000 // 0000 00...
F0000000 // 1111 00...
70000000 // 0111 00...
70000000 // 0111 00...
70000000 // 0111 00...
70000000 // 0111 00...
F8000000 // 1111 10...
</PRE>

<P>With some squinting (or filling in squares on graph paper), this should
look suspiciously like an "i". Sloup translates this to a soup entry as
follows:

<PRE>{name: infoIcon,
width: 5,
bitmap: {bounds: {left: 0, top: 0, right: 5, bottom: 9}
         bits: ...}
}
</PRE>

<P>Later, you could create a picture button, in Newt for example, to use this bitmap as an icon:

<PRE>{_proto: protoPictureButton,
...
icon: :GetPictAsBits("Bitmaps", "infoIcon"),
}</PRE>

<P>In Newt's Cape you could access it via a URL:

<PRE>&lt;IMG SRC="bitmaps/infoIcon" ALT="Info Icon"&gt;</PRE>

<P>How would you create these bitmaps? In addition to creating by hand or
using some of the examples that come with Newt, you can use the icon editor
in ResEdit (on a Mac), open the hexadecimal editor template, do a Select All
and copy (or copy it in segments if &gt; 32K), then paste into a text
editor. On Mac or Windows, Newt's Cape users can use Newt's Cape Graphic
Converter to convert GIF or (PICT on Mac) or (BMP on Windows) to Bitmap
format. On the Newton, you can copy bitmap entries (using Newt) from ROM or
existing applications to a soup, and then DUMP! the entries to your desktop,
then copy/paste as text into your own .bit file. See <A
HREF="../toolinfo.htm">latest Sloup tools</A>

<P>You can transfer and create fairly large bitmaps -- largest I have used
so far is 230x230 for the dot2dot.nwt example (though generally you might
use a PICT for some graphics). For icons and masks in the Extras Drawer,
it's recommended that bitmaps be no larger than 32x29.

<P>If the name of a bitmap is suffixed with !, this is interpreted (just
like NTK) as a mask. When an icon is highlighted, its region inverts by
default. You can specify a different mask via ! (this assumes that the
regularly named bitmap already exists, i.e., occurred earlier in the file or
transferred separately). This adds a mask field to the existing bitmap soup
entry (and does not increment the "Entries" count). Here is an example
(pictbuts.bit; I've truncated the lines):

<PRE>Bitmaps![{structure: 'slot, path: 'name, type: 'symbol},]
{name: 'symbol, width: "int", bitmap: "bitmap"}
alarm clock	24	0000000000000000000000000000000000000000000000...
alarm clock!	24	0008000001004000000800000880800004000400020010...
light bulb	17	03C000000FF000001C1C00003006000060030000600300...
light bulb!	36	0000000000000000000020100000000000002030000000...
plane	22	60000000580038002600C80011C10C000A42100004B41000050820...
scales	24	0018000000180000001800000000000000180000007E00001F...
BYE!
</PRE>

<P>Exercise for the reader: Name those Bits

<PRE>WhatIsThis	16	!\
08000000\
54000000\
AA000000\
AA000000\
95000000\
551C0000\
4BE20000\
40030000\
87050000\
8A810000\
80020000\
400C0000\
40300000\
20400000\
20800000\
20800000
</PRE>

<H2><A NAME="Gray Scale Bitmaps">Gray Scale Bitmaps</A></H2>

<P>For NOS 2.1 systems, you can transfer gray scale bitmaps (assuming that
you have a tool that creates them). For a 4-gray bitmap, each 2 bits
represents a pixel; for 16-grays, 4 bits represents a pixel. You need to
include an additional entryspec field bitdepth to indicate the number of
bits (no bitDepth or bitDepth: 1 means black and white), and Sloup creates
the correct picture structure. These pictures can be included in Newt's Cape
books or viewed with BitSound 1.5 (or greater). For example:

<PRE>...
{name: "string", width: "int", bitdepth: "int", bitmap: "bitmap"}
</PRE>

<H2><A NAME="PICT">PICT</A></H2>

<P>A PICT is a different data structure from a flat bitmap. A Newton PICT is
basically the same as the old Mac PICT1 format (most Mac applications use
PICT2, but you could paste into HyperCard as one way to convert to PICT1
first; or use Newt's Cape Graphic Converter).

<P>Transferring a PICT is easier since you don't need to know the width.
These can go in the same soup as bitmaps since they have the same basic slot
structure, and can be used in the icon slot of a clPictureView. However,
since PICTs cannot be used on some MPs in a protoPictureButton or as an
application icon in Extras, you may wish to store them in a separate soup.
Using Bitmap or PICT in a clPictureView depends on which format is available
to you, and which is more compact.

<PRE>Bitmaps![{structure: 'slot, path: 'name, type: 'symbol},]
{name: 'symbol, bitmap: "picture"}
lightNewt 	00C9000000000022001D1101A00082A0008E01000A0...
BYE!
</PRE>

<H2><A NAME="Sounds">Sounds</A></H2>

<P>Sounds can also be transferred. However, since even "short" sounds can be
rather large, you may run into heap limits on 1.x Newtons. You need to know
whether the sound was sampled at a 11KHz or 22KHz sampling rate, which is
specified as a real number 11013.2 or 22026.4, respectively.

<PRE>Sounds![{structure: 'slot, path: 'name, type: 'symbol},] //heavymet.snd
{name: 'symbol, samplingRate: "real", sound: "sound"}
sine	22026.4	F26C000000003FB0FFFFFFE3944F27243D6381...[~14K]
BYE!
Sounds![{structure: 'slot, path: 'name, type: 'symbol},] //soundadv.snd
{name: 'symbol, samplingRate: "real", sound: "sound"}
Boing	11013.2	80808080808080808080808080808080808080...[~15K]
BYE!
</PRE>

<P>To use a sound on the Newton, from NewtDevEnv, you could do:

<PRE>PlaySound(:GetSound("Sounds","boing"))
</PRE>

<P>You could also embed a sound in a Newt's Cape book by using the :GetSound
development method inside META.

<P>The largest sound I've transferred so far is the several-second
"dadadada" sound from the False Alarm (falsalrm.nwt) example. This began as
a ~31K binary resource on the Mac, extracted via several copy&amp;pastes as
~63K of hex text, and converted into a ~32K soup entry on the Newton. I
don't know the internal format of a sound string. It currently represents an
uncompressed sample. If you send me pointers to info on sound formats and
tools, I'll be glad to propagate to other users.

<P>The <A HREF="../newtpkgs.htm#BitSound">Newt BitSound application</A>
allows you to display bitmaps/PICTs and play sounds -- both the built-in ROM
frames and those in soups.


<H2><A NAME="Resources">Resources</A></H2>

<P>You can also transfer other resources such as device codes for remote
control applications for TVs and VCRs, e.g., for the irremote.nwt and
tvpad.nwt examples.

<PRE>IRCD![{structure: 'slot, path: 'name, type: 'symbol},] // irremote.nwt
{name: 'symbol, resource: "resource"}
RC5Play0	!\
706C79300000035200000001000000200000008000000012000000010000000200000001\
...
</PRE>

<P>Again, I don't know the internal format of these strings -- but they can
copied/pasted directly from ResEdit. In Newt (assuming you have platform
functions installed), e.g.,

<PRE>:SendRemoteControlCode(data,:GetNamedResource("IRCD", "RC5Play0",'resource),1)
</PRE>

<H2><A NAME="binary:packageEntry">binary:packageEntry</A></H2>

<P>You can also create other binary types using the binary: prefix in an
entrySpec. For example, to dump a package named ReStartPkg, you could do:

<PRE>Package
{packageName: "ReStartPkg", packageEntry: "binary:packageEntry"}
DUMP!
</PRE>
<P>To install a package named ReStartPkg, you could do:
<PRE>Package
{packageName: "ReStartPkg", packageEntry: "binary:packageEntry"}
ReStartPkg	!\
7061636B616765307878787800000000000000010000004A004A001600000F7000000000\
...
BYE!
</PRE>


<H2>Speed</H2>

<P>If you have many and/or large files, bitmap, PICT, sound or other
resources, you may wish to consider registering for Sloup (or Newt) so that
you can get other versions which allow faster connections and faster
resource conversion.

<HR>

<P>Version 2.1. Last updated: Jan 1998

<UL>
<LI><A HREF="#Line Continuations">Top</A>
<LI>Next: <A HREF="slrpsoup.htm">Applications, Soups</A>
<LI><A HREF="slrptoc.htm">Table of Contents</A>
<LI>Index: <A HREF="slrpindx.htm#A">A</A> | <A HREF="slrpindx.htm#B">B</A> | <A HREF="slrpindx.htm#C">C</A> | <A HREF="slrpindx.htm#D">D</A> | <A HREF="slrpindx.htm#E">E</A> | <A HREF="slrpindx.htm#F">F</A> | <A HREF="slrpindx.htm#G">G</A> | <A HREF="slrpindx.htm#H">H</A> | <A HREF="slrpindx.htm#I">I</A> | <A HREF="slrpindx.htm#J">J</A> | <A HREF="slrpindx.htm#K">K</A> | <A HREF="slrpindx.htm#L">L</A> | <A HREF="slrpindx.htm#M">M</A> | <A HREF="slrpindx.htm#N">N</A> | <A HREF="slrpindx.htm#O">O</A> | <A HREF="slrpindx.htm#P">P</A> | <A HREF="slrpindx.htm#Q">Q</A> | <A HREF="slrpindx.htm#R">R</A> | <A HREF="slrpindx.htm#S">S</A> | <A HREF="slrpindx.htm#T">T</A> | <A HREF="slrpindx.htm#U">U</A> | <A HREF="slrpindx.htm#V">V</A> | <A HREF="slrpindx.htm#W">W</A> | <A HREF="slrpindx.htm#X">X</A> | <A HREF="slrpindx.htm#Y">Y</A> | <A HREF="slrpindx.htm#Z">Z</A>
<LI><A HREF="mailto:weyer@kagi.com">weyer@kagi.com</A>
<LI><A HREF="../index.htm">Steve's releases page</A>
</UL>

</BODY></HTML>
